ESP-IDF uses the open source lwIP lightweight TCP/IP stack. The ESP-IDF version of lwIP (esp-lwip) has some modifications and additions compared to the upstream project.

ESP-IDF supports the following lwIP TCP/IP stack functions:

BSD Sockets API

Netconn API is enabled but not officially supported for ESP-IDF applications

Some common lwIP “app” APIs are supported indirectly by ESP-IDF:

DHCP Server & Client are supported indirectly via the ESP-NETIF functionality

Simple Network Time Protocol (SNTP) is supported via the lwip/include/apps/sntp/sntp.h lwip/lwip/src/inlude/lwip/apps/sntp.h functions (see also SNTP Time Synchronization)

ICMP Ping is supported using a variation on the lwIP ping API. See ICMP Echo.

NetBIOS lookup is available using the standard lwIP API. protocols/http_server/restful_server has an option to demonstrate using NetBIOS to look up a host on the LAN.

mDNS uses a different implementation to the lwIP default mDNS (see mDNS Service), but lwIP can look up mDNS hosts using standard APIs such as gethostbyname() and the convention hostname.local, provided the CONFIG_LWIP_DNS_SUPPORT_MDNS_QUERIES setting is enabled.

The BSD Sockets API is a common cross-platform TCP/IP sockets API that originated in the Berkeley Standard Distribution of UNIX but is now standardized in a section of the POSIX specification. BSD Sockets are sometimes called POSIX Sockets or Berkeley Sockets.

As implemented in ESP-IDF, lwIP supports all of the common usages of the BSD Sockets API.

A wide range of BSD Sockets reference material is available, including:

Single UNIX Specification BSD Sockets page

Berkeley Sockets Wikipedia page

A number of ESP-IDF examples show how to use the BSD Sockets APIs:

protocols/sockets/tcp_server

protocols/sockets/tcp_client

protocols/sockets/udp_server

protocols/sockets/udp_client

protocols/sockets/udp_multicast

protocols/http_request (Note: this is a simplified example of using a TCP socket to send an HTTP request. The ESP HTTP Client is a much better option for sending HTTP requests.)

The following BSD socket API functions are supported. For full details see lwip/lwip/src/include/lwip/sockets.h.

socket()

bind()

accept()

shutdown()

getpeername()

getsockopt() & setsockopt() (see Socket Options)

close() (via Virtual filesystem component)

read(), readv(), write(), writev() (via Virtual filesystem component)

recv(), recvmsg(), recvfrom()

send(), sendmsg(), sendto()

select() (via Virtual filesystem component)

poll() (Note: on ESP-IDF, poll() is implemented by calling select internally, so using select() directly is recommended if a choice of methods is available.)

fcntl() (see fcntl)

Non-standard functions:

ioctl() (see ioctls)

Note

Some lwIP application sample code uses prefixed versions of BSD APIs, for example lwip_socket() instead of the standard socket(). Both forms can be used with ESP-IDF, but using standard names is recommended.

BSD Socket error handling code is very important for robust socket applications. Normally the socket error handling involves the following aspects:

Detecting the error.

Geting the error reason code.

Handle the error according to the reason code.

In lwIP, we have two different scenarios of handling socket errors:

Socket API returns an error. For more information, see Socket API Errors.

select(int maxfdp1, fd_set *readset, fd_set *writeset, fd_set *exceptset, struct timeval *timeout) has exception descriptor indicating that the socket has an error. For more information, see select() Errors.

We can know that the socket API fails according to its return value.

When socket API fails, the return value doesn’t contain the failure reason and the application can get the error reason code by accessing errno. Different values indicate different meanings. For more information, see .

Example: